20.7.13 Accessing Mouse Events

This section describes convenient functions for accessing the data in a mouse button or motion event. Keyboard event data can be accessed using the same functions, but data elements that aren’t applicable to keyboard events are zero or nil.

The following two functions return a mouse position list (see Click Events), specifying the position of a mouse event.

Function: event-start event

This returns the starting position of event.

If event is a click or button-down event, this returns the location of the event. If event is a drag event, this returns the drag’s starting position.

Function: event-end event

This returns the ending position of event.

If event is a drag event, this returns the position where the user released the mouse button. If event is a click or button-down event, the value is actually the starting position, which is the only position such events have.

Function: posnp object

This function returns non-nil if object is a mouse position list, in either of the formats documented in Click Events); and nil otherwise.

These functions take a mouse position list as argument, and return various parts of it:

Function: posn-window position

Return the window that position is in. If position represents a location outside the frame where the event was initiated, return that frame instead.

Function: posn-area position

Return the window area recorded in position. It returns nil when the event occurred in the text area of the window; otherwise, it is a symbol identifying the area in which the event occurred.

Function: posn-point position

Return the buffer position in position. When the event occurred in the text area of the window, in a marginal area, or on a fringe, this is an integer specifying a buffer position. Otherwise, the value is undefined.

Function: posn-x-y position

Return the pixel-based x and y coordinates in position, as a cons cell (x . y). These coordinates are relative to the window given by posn-window.

This example shows how to convert the window-relative coordinates in the text area of a window into frame-relative coordinates:

(defun frame-relative-coordinates (position)
  "Return frame-relative coordinates from POSITION.
POSITION is assumed to lie in a window text area."
  (let* ((x-y (posn-x-y position))
         (window (posn-window position))
         (edges (window-inside-pixel-edges window)))
    (cons (+ (car x-y) (car edges))
          (+ (cdr x-y) (cadr edges)))))

Function: posn-col-row position

This function returns a cons cell (col . row), containing the estimated column and row corresponding to buffer position in position. The return value is given in units of the frame’s default character width and default line height (including spacing), as computed from the x and y values corresponding to position. (So, if the actual characters have non-default sizes, the actual row and column may differ from these computed values.)

Note that row is counted from the top of the text area. If the window given by position possesses a header line (see Header Lines), it is not included in the row count.

Function: posn-actual-col-row position

Return the actual row and column in position, as a cons cell (col . row). The values are the actual row and column numbers in the window given by position. See Click Events, for details. The function returns nil if position does not include actual position values; in that case posn-col-row can be used to get approximate values.

Note that this function doesn’t account for the visual width of characters on display, like the number of visual columns taken by a tab character or an image. If you need the coordinates in canonical character units, use posn-col-row instead.

Function: posn-string position

Return the string object in position, either nil, or a cons cell (string . string-pos).

Function: posn-image position

Return the image object in position, either nil, or an image (image ...).

Function: posn-object position

Return the image or string object in position, either nil, an image (image ...), or a cons cell (string . string-pos).

Function: posn-object-x-y position

Return the pixel-based x and y coordinates relative to the upper left corner of the object in position as a cons cell (dx . dy). If the position is on buffer text, return the relative position of the buffer-text character closest to that position.

Function: posn-object-width-height position

Return the pixel width and height of the object in position as a cons cell (width . height). If the position is a buffer position, return the size of the character at that position.

Function: posn-timestamp position

Return the timestamp in position. This is the time at which the event occurred, in milliseconds.

These functions compute a position list given particular buffer position or screen position. You can access the data in this position list with the functions described above.

Function: posn-at-point &optional pos window

This function returns a position list for position pos in window. pos defaults to point in window; window defaults to the selected window.

posn-at-point returns nil if pos is not visible in window.

Function: posn-at-x-y x y &optional frame-or-window whole

This function returns position information corresponding to pixel coordinates x and y in a specified frame or window, frame-or-window, which defaults to the selected window. The coordinates x and y are relative to the frame or window used. If whole is nil, the coordinates are relative to the window text area, otherwise they are relative to the entire window area including scroll bars, margins and fringes.